Add ouroboros-consensus:tracing sublibrary - #2244
Merged
Merged
Conversation
jasagredo
requested review from
bladyjoker,
dnadales,
geo2a and
nfrisby
as code owners
August 27, 2026 13:17
jasagredo
force-pushed
the
js/tracing-instances
branch
2 times, most recently
from
August 27, 2026 13:32
b003a0e to
7b0838e
Compare
jasagredo
force-pushed
the
js/tracing-instances
branch
from
September 3, 2026 15:21
e9b2bd8 to
8f27e3f
Compare
dnadales
reviewed
Sep 4, 2026
jasagredo
force-pushed
the
js/tracing-instances
branch
2 times, most recently
from
September 9, 2026 12:08
332726c to
b73febc
Compare
7 of 12 tasks
jasagredo
force-pushed
the
js/tracing-instances
branch
from
September 16, 2026 10:44
b73febc to
80ae926
Compare
jasagredo
added this pull request to stack #2296
September 16, 2026 10:44
jasagredo
force-pushed
the
js/tracing-instances
branch
from
September 16, 2026 11:11
80ae926 to
232e47e
Compare
jasagredo
force-pushed
the
js/tracing-instances
branch
from
September 16, 2026 11:28
232e47e to
f86d8dc
Compare
jasagredo
force-pushed
the
js/tracing-instances
branch
2 times, most recently
from
September 28, 2026 09:16
2a51544 to
cf25039
Compare
jasagredo
removed this pull request from stack #2296
September 28, 2026 09:16
Introduce a new public sublibrary 'tracing' with instances for Consensus types, moved from cardano-node.
Moving it from cardano-node/cardano-api.
Reimplement, off cardano-api, the Shelley-era JSON rendering helpers that the era tracing instances need: bech32 stake/reward addresses (CIP-19, via the bech32 package), hex script hashes, and an era-generic script-purpose renderer built on cardano-ledger-api's AnyEraScript projections (replacing cardano-api's per-era Alonzo/Conway plutus-purpose rendering and its ShelleyBasedEra/ AlonzoEraOnwards era witnesses). Output matches cardano-api's.
Move Cardano.Node.Tracing.Era.Byron to Ouroboros.Consensus.Tracing.Era.Byron; inline the trivial textShow helper (its only cardano-api use) and drop the imports the old -Wno-unused-imports hack was masking.
The list of traced types was hand-written and had drifted from Consensus.Tracers: six top-level tracers were missing, all of them ones whose type carries a peer or has no block parameter, which is why they were easy to overlook. TraceGDDEvent, Jumping.TraceEventCsj, Jumping.TraceEventDbf, BlockFetch.TraceFetchClientState, TraceDecisionEvent, KESAgentClientTrace They bring 14 more undocumented namespaces into knownUndocumented, 13 of them KESAgentClientTrace's -- an entire tracer whose messages carry no documentation at all, and which nothing was asserting anything about until now. The peer type is a stand-in: no MetaTrace method looks at it, so this uses () rather than pulling in the node's address types.
LedgerDB, ImmutableDB, VolatileDB, PerasCertDB and PerasVoteDB do not have tracers of their own. ChainDbArgs.updateTracer derives each from the ChainDB tracer, and ChainDB.TraceEvent's allNamespaces maps all of their namespaces in under LedgerEvent, ImmDbEvent, VolatileDbEvent and so on -- cardano-node has no tracer for any of them either. Listing them alongside ChainDB.TraceEvent meant every one of their namespaces was checked twice under two different names, and appeared twice in knownUndocumented: once as ChunkValidation.InvalidChunkFile and again as ImmDbEvent.ChunkValidation.InvalidChunkFile, once as Flavor.V2.BackendTrace.LSM.LSMSnap and again as LedgerEvent.Flavor.V2.BackendTrace.LSM.LSMSnap. Keep ChainDB.TraceEvent, which reaches all of them, and drop the 17 duplicated ratchet entries.
'maximumDef' was the only thing taken from it, in two severity computations. 'foldr max' over the same list gives the same answer, and the main library does not depend on cardano-prelude either, so this keeps a public library out of the dependency tree entirely.
cardano-ledger-api does ship a COMPLETE pragma over the seven
AnyEra*Purpose synonyms, so the wildcard was not future-proofing: it was
reachable today, and a Dijkstra guarding redeemer rendered as
{"kind":"UnknownPlutusPurpose"} in the logs.
Match all seven and drop the wildcard, so that the next era is a compile
error here rather than a marker in an operator's logs. Guarding has no
cardano-api rendering to preserve, so its item renders directly (like
spending and rewarding) and its witness index name is ours.
'purposesByItem' only covered three of the six Conway purposes, leaving
certifying, voting and proposing unpinned -- and those are exactly the
{"item": ...}-wrapped ones the comment above warns about, so the ones
most likely to drift. 'renderTxIn' had no entry either.
Add them, plus the guarding purpose, which needs the Dijkstra era and so
also exercises the other AnyEraScript instance rather than only Conway's.
cardano-node removed the instances for [TraceLabelPeer peer (FetchDecision [Point header])] under IntersectMBO/cardano-node#6667: nothing emits that list, and its Accept/Decline/EmptyPeersFetch namespaces were the stale ones the configuration consistency check rejected. The MetaTrace instance for FetchDecision goes with them; its metricsDocFor advertised a connectedPeers metric that no asMetrics ever produced. What remains is LogFormatting (FetchDecision [Point header]), which TraceDecisionEvent's own rendering needs, matching cardano-node master.
The docstring claimed to catch a namespace left out of 'allNamespaces', but every check iterates 'allNamespaces' itself and 'namespaceFor' is never called, so that mistake -- and a typo appearing in both places -- still passes. Catching it needs trace values, which these types have no 'Arbitrary' or 'Enum' to produce, so narrow the wording instead.
'tracing/golden' sits outside the test component's hs-source-dirs, so without an 'extraSrcFiles' entry haskell.nix pruned it out of the component source, and without '--no-create' tasty-golden then created the missing file and reported a pass. The Nix check was green without comparing anything. Key the golden directories by test name so that adding one is a single line and cannot forget either half.
'tracing' is public API -- HasIssuer, ConvertTxId, and every log shape an operator parses -- but it was not in the list the check walks, so a later change to its .hs files would never ask for a fragment. Its path is the directory itself, since that is its hs-source-dirs.
jasagredo
force-pushed
the
js/tracing-instances
branch
from
September 29, 2026 12:09
e62c4cc to
1dd48ca
Compare
jasagredo
force-pushed
the
js/tracing-instances
branch
from
September 29, 2026 14:11
56101d9 to
a95d5fa
Compare
geo2a
approved these changes
Sep 29, 2026
jasagredo
added this pull request to stack #2336
September 29, 2026 15:58
jasagredo
removed this pull request from stack #2336
September 29, 2026 15:59
jasagredo
added this pull request to stack #2337
September 29, 2026 16:00
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Move the tracing instances from cardano-node to ouroboros-consensus.